<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Debugging: Various Debuggingc Aids -->

<div class='section'>4.1 Trace</div>
	The <font class="italic">trace</font> facility allows the user to trace some functions.
When a function is traced, certain special actions will be taken when it is
called, and when it returns.  The function <font class="lisp">trace</font> allows the user to
specify this.

	The trace facility is closely compatible with Maclisp.
Although the functions of the trace system which are presented here are
really functions, they are implemented as special forms because that
is the way Maclisp did it.

	Alternatively, you can use the trace system by clicking "trace"
in the system menu, or by using the "meta-X trace" command in the editor.
This allows you to select the trace options from a menu instead of having
to remember the following syntax.

<div class="defspec"><font class='exdent'><font class='funcname'>trace</font><font class="italic"> Special Form</font></font><br>
	A <font class="lisp">trace</font> form looks like:
<pre class="lisp">
(trace <font class="italic">spec-1</font> <font class="italic">spec-2</font> ...)
</pre>

	A <font class="italic">spec</font> may be either a symbol, which is interpreted as a function
name, or a list of the form <font class="lisp">(<font class="italic">function-name</font> <font class="italic">option-1</font> <font class="italic">option-2</font> ...)</font>.
If <font class="italic">spec</font> is a symbol, it is the same as giving the function name with
no options.  Some options take "arguments", which should be given immediately
following the option name.
</div>

	The following options exist:
.table 3
.item :break <font class="italic">pred</font>
Causes a breakpoint to be entered after printing
the entry trace information but before applying the traced function to its
arguments, if and only if <font class="italic">pred</font> evaluates to non-<font class="lisp">nil</font>.
.item :exitbreak <font class="italic">pred</font>
This is just like <font class="lisp">break</font> except that the
breakpoint is entered after the function has been executed and the exit trace information
has been printed, but before control returns.
.item :step
Causes the function to be single-stepped whenever it is called.
See the documentation on the step facility below.
.item :entrycond <font class="italic">pred</font>
Causes trace information to be printed on function
entry only if <font class="italic">pred</font> evaluates to non-<font class="lisp">nil</font>.
.item :exitcond <font class="italic">pred</font>
Causes trace information to be printed on function
exit only if <font class="italic">pred</font> evaluates to non-<font class="lisp">nil</font>.
.item :cond <font class="italic">pred</font>
This specifies both <font class="lisp">exitcond</font> and <font class="lisp">entrycond</font>
together.
.item :wherein <font class="italic">function</font>
Causes the function to be traced only when called, directly or indirectly,
from the specified function <font class="italic">function</font>.  One can give several trace specs to
<font class="lisp">trace</font>, all specifying the same function but with different <font class="lisp">wherein</font>
options, so that the function is traced in different ways when called from
different functions.
.item :argpdl <font class="italic">pdl</font>
This specifies a symbol <font class="italic">pdl</font>, whose value is
initially set to <font class="lisp">nil</font> by <font class="lisp">trace</font>.  When the function is traced, a
list of the current recursion level for the function, the function's
name, and a list of arguments is consed onto the <font class="italic">pdl</font> when the
function is entered, and cdr'ed back off when the function is exited.
The <font class="italic">pdl</font> can be inspected from within a breakpoint, for example, and
used to determine the very recent history of the function. This option
can be used with or without printed trace output.  Each function can be
given its own pdl, or one pdl may serve several functions.
.item :entryprint <font class="italic">form</font>
The <font class="italic">form</font> is evaluated and the value is included in the trace message
for calls to the function.  You can give this option more than once, and
all the values will appear, preceded by <font class="lisp">\\</font>.
.item :exitprint <font class="italic">form</font>
The <font class="italic">form</font> is evaluated and the value is included in the trace message
for returns from the function.  You can give this option more than once, and
all the values will appear, preceded by <font class="lisp">\\</font>.
.item :print <font class="italic">form</font>
The <font class="italic">form</font> is evaluated and the value is included in the trace messages
for both calls to and returns from the function.  You can give this option more than once, and
all the values will appear, preceded by <font class="lisp">\\</font>.
.item :entry <font class="italic">list</font>
This specifies a list of arbitrary forms whose
values are to be printed along with the usual entry-trace.  The list of
resultant values, when printed, is preceded by a <font class="lisp">\\</font> to separate it
from the other information.
.item :exit <font class="italic">list</font>
This is similar to <font class="lisp">entry</font>, but specifies expressions
whose values are printed with the exit-trace.  Again, the list of
values printed is preceded by <font class="lisp">\\</font>.
.item :arg :value :both nil
These specify which of the usual trace
printout should be enabled.  If <font class="lisp">arg</font> is specified, then on function
entry the name of the function and the values of its arguments will be
printed.  If <font class="lisp">value</font> is specified, then on function exit the returned
value(s) of the function will be printed.  If <font class="lisp">both</font> is specified,
both of these will be printed.  If <font class="lisp">nil</font> is specified, neither will
be printed.  If none of these four options are specified the default is
to <font class="lisp">both</font>.  If any further <font class="italic">options</font> appear after one of these,
they will not be treated as options! Rather, they will be considered to
be arbitrary forms whose values are to be printed on entry and/or exit
to the function, along with the normal trace information. The values
printed will be preceded by a <font class="lisp">//</font>, and follow any values specified
by <font class="lisp">entry</font> or <font class="lisp">exit</font>.  Note that since these options "swallow" all
following options, if one is given it should be the last option
specified.
.end_table

If the variable <font class="lisp">arglist</font> is used in any of the expressions given for
the <font class="lisp">cond, break, entry, </font>or<font class="lisp"> exit</font> options, or after the <font class="lisp">arg,
value, both, </font>or<font class="lisp"> nil</font> option, when those expressions are evaluated
the value of <font class="lisp">arglist</font> will be bound to a list of the arguments
given to the traced function.  Thus 
<pre class="lisp">
(trace (foo break (null (car arglist))))
</pre>
would cause a break in <font class="lisp">foo</font> if and only if the first
argument to <font class="lisp">foo</font> is <font class="lisp">nil</font>.
<font class="lisp">arglist</font> should have a colon, but it is omitted because this is
the name of a system function and therefore global.


Similarly, the variable <font class="lisp">si:fnvalues</font> will
be a list of the resulting values of the traced function.  For obvious
reasons, this should only be used with the <font class="lisp">exit</font> option.

The trace specifications may be "factored."  For example,
<pre class="lisp">
(trace ((foo bar) wherein baz value))
<font class="main">is equivalent to</font>
(trace (foo wherein baz value) (bar wherein baz value))
</pre>
Since a list as a function name is interpreted as a list of
functions, non-atomic function names (see (fdefine-fun))
are specified as follows:
<pre class="lisp">
(trace (:function (:method foo-class bar) :break t))
</pre>

All output printed by trace can be ground into an indented,
readable format, by simply setting the variable <font class="lisp">sprinter</font> to <font class="lisp">t</font>.
Setting <font class="lisp">sprinter</font> to <font class="lisp">nil</font> changes the output back to use
the ordinary print function, which is faster and uses less
storage but is less readable for large list structures.
This is not yet supported.

<font class="lisp">trace</font> returns as its value a list of names of all functions
traced; for any functions traced with the <font class="lisp">wherein</font>
option, say <font class="lisp">(trace (foo wherein bar))</font>, instead of putting
just <font class="lisp">foo</font> in the list it puts in a 3-list <font class="lisp">(foo wherein bar)</font>.

If you attempt to specify to <font class="lisp">trace</font> a function already
being traced, <font class="lisp">trace</font> calls <font class="lisp">untrace</font> before setting up the new
trace.

It is possible to call <font class="lisp">trace</font> with no arguments.  <font class="lisp">(trace)</font>
evaluates to a list of all the functions currently
being traced.

<div class="defspec"><font class='exdent'><font class='funcname'>untrace</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">untrace</font> is used to undo the effects of <font class="lisp">trace</font> and restore
functions to their normal, untraced state.  The argument
to <font class="lisp">untrace</font> for a given function should be what
<font class="lisp">trace</font> returned for it; i.e. if <font class="lisp">trace</font> returned <font class="lisp">foo</font>, use
<font class="lisp">(untrace foo)</font>; if <font class="lisp">trace</font> returned <font class="lisp">(foo wherein bar)</font> use
<font class="lisp">(untrace (foo wherein bar))</font>.  <font class="lisp">untrace</font> will take multiple
specifications, e.g. <font class="lisp">(untrace foo quux (bar wherein baz) fuphoo)</font>.
Calling <font class="lisp">untrace</font> with no arguments will untrace all functions currently being traced.
</div>

Unlike Maclisp, if there is an error <font class="lisp">trace</font> (or <font class="lisp">untrace</font>) will
invoke
'c shaft you by invoking
the error system and give an English message, instead of returning
lists with question marks in them.  Also, the <font class="lisp">remtrace</font> function
is not provided, since it is unnecessary.

.defvar trace-compile-flag
If the value of <font class="lisp">trace-compile-flag</font> is non-<font class="lisp">nil</font>, the functions
created by <font class="lisp">trace</font> will get compiled, allowing you to trace special
forms such as <font class="lisp">cond</font> without interfering with the execution of the
tracing functions.  The default value of this flag is <font class="lisp">nil</font>.
.end_defvar

<div class='section'>4.2 The Stepper</div>
	The Step facility provides the ability to follow every step of
the evaluation of a form, and examine what is going on.  It is
analogous to a single-step proceed facility often found in
machine-language debuggers.  If your program is doing something
strange, and it isn't obvious how it's getting into its strange state,
then the stepper is for you.

.subsection "How to Get Into the Stepper."

	There are two ways to enter the stepper.  One is by use of the
<font class="lisp">step</font> function.

<div class='defun'><font class='exdent'><font class='funcname'>step <font class='italic' color='purple'>form</font></font></font><br>
	This evaluates <font class="italic">form</font> with single stepping.  It returns
the value of <font class="italic">form</font>.
</div>

	For example, if you have a function named <font class="lisp">foo</font>, and typical arguments
to it might be <font class="lisp">t</font> and <font class="lisp">3</font>, you could say
<pre class="lisp">
(step '(foo t 3))
</pre>
and the form <font class="lisp">(foo t 3)</font> will be evaluated with single stepping.

	The other way to get into the stepper is to use the <font class="lisp">step</font> option 
of <font class="lisp">trace</font> (see (trace-fun)).  If a function is traced with the <font class="lisp">step</font> option, then
whenever that function is called it will be single stepped.

	Note that any function to be stepped must be interpreted; that is, it
must be a lambda-expression.  Compiled code cannot be stepped by the stepper.

.subsection "How to Use the Stepper"

	When evaluation is proceeding with single stepping, before any
form is evaluated, it is (partially) printed out, preceded by a forward
arrow (<font class="lisp"></font>) character  When a macro is expanded, the expansion is
printed out preceded by a double arrow (<font class="lisp"></font>) character.  When a form
returns a value, the form and the values are printed out preceded by a
backwards arrow (<font class="lisp"></font>) character; if there is more than one value being
returned, an and-sign (<font class="lisp"></font>) character is printed between the values. 

	Since the forms may be very long, the stepper does not print all
of a form; it truncates the printed representation after a certain number
of characters.  Also, to show the recursion pattern of who calls whom in
a graphic fashion, it indents each form proportionally to its level
of recursion.

	After the stepper prints any of these things, it waits for a
command from the user.  There are several commands to tell the stepper
how to proceed, or to look at what is happening. The commands are:
.table 1
.item Control-N (Next)
Step to the Next thing.  The stepper continues until the next thing
to print out, and it accepts another command.
.item Space
Go to the next thing at this level.  In other words, continue to
evaluate at this level, but don't step anything at lower levels.  This is a good
way to skip over parts of the evaluation that don't interest you.
.item Control-U (Up)
Continue evaluating until we go up one level.  This is like
the space command, only more so; it skips over anything on the current level
as well as lower levels.
.item Control-X (eXit)
Exit; finish evaluating without any more stepping.
.item Control-T (Type)
Retype the current form in full (without truncation).
.item Control-G (Grind)
Grind (i.e. prettyprint) the current form.
.item Control-E (Editor)
Editor escape (enter the Eine editor).
.item Control-B (Breakpoint)
Breakpoint.  This command puts you into a breakpoint (i.e.
a read-eval-print loop) from which you can examine the values of
variables and other aspects of the current environment.  From
within this loop, the following variables are available:
.table 3
.item step-form
which is the current form.
.item step-values
which is the list of returned values.
.item step-value
which is the first returned value.
.end_table
If you change the values of these variables, it will work.
.item Control-L
Clear the screen and redisplay the last 10. pending forms (forms
which are being evaluated).
.item Meta-L
Like Control-L, but doesn't clear the screen.
.item Control-Meta-L
Like Control-L, but redisplays all pending forms.
.item ? or Help
Prints documentation on these commands.
.end_table
	It is strongly suggested that you write some little function
and try the stepper on it.  If you get a feel for what the stepper does
and how it works, you will be able to tell when it is the right thing to use
to find bugs.

<div class='section'>4.3 The MAR</div>
	The MAR facility allows any word or contiguous set of words to
be monitored constantly, and can cause an error if the words are
referenced in a specified manner.  The name MAR is from the similar
device on the ITS PDP-10's; it is an acronym for "Memory Address
Register".  The MAR checking is done by the Lisp Machine's memory
management hardware, and so the speed of general execution when the MAR is
enabled is not significantly slowed down.  However, the speed of accessing
pages of memory containing the locations being checked is slowed down, since every
reference involves a microcode trap.

	These are the functions that control the MAR:

<div class='defun'><font class='exdent'><font class='funcname'>set-mar <font class='italic' color='purple'>location cycle-type &optional n-words</font></font></font><br>
	The <font class="lisp">set-mar</font> function clears any previous setting of the
MAR, and sets the MAR on <font class="italic">n-words</font> words, starting at <font class="italic">location</font>.
<font class="italic">location</font> may be any object.  <font class="italic">n-words</font> currently defaults to 1,
but eventually it will default to the size of the object.
<font class="italic">cycle-type</font> says under what conditions to trap.  <font class="lisp">:read</font> means that
only reading the location should cause an error, <font class="lisp">:write</font> means that
only writing the location should, <font class="lisp">t</font> means that both should.
To set the MAR on the value of a variable, use
<pre class="lisp">
(set-mar (value-cell-location <font class="italic">symbol</font>) :write)
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>clear-mar
This <font class='italic' color='purple'>turns off the MAR.  Restarting the machine disables the</font></font></font><br>
MAR but does not turn it off, i.e. references to the MARed pages
are still slowed down.  <font class="lisp">clear-mar</font> does not currently speed
things back up until the next time the pages are swapped out;
this may be fixed some day.
</div>

.defvar si:%mar-low
.defvar1 si:%mar-high
	These two fixnums are the inclusive boundaries of the area
of memory monitored by the MAR.  The values of these variables live
inside the microcode.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>mar-mode
<font class="lisp">(mar-mode)</font> <font class='italic' color='purple'>returns a symbol indicating the current state of</font></font></font><br>
the MAR.  It returns one of:
.table 3
.item nil
The MAR is not set.
.item :read
The MAR will cause an error if there is a read.
.item :write
The MAR will cause an error if there is a write.
.item t
The MAR will cause an error if there is any reference.
.end_table
</div>

Note that using the MAR makes the pages on which it is set
considerably slower to access, until the next time they are
swapped out and back in again after the MAR is shut off.
Also, use of the MAR currently breaks the read-only feature
if those pages were read-only.  Currently it is not possible
to proceed from a MAR trrap, because some machine state is lost.
Eventually, most MAR traps will be continuable.
.eof
</body>
</html>

